Move documentation to inline comments: GtkSizeGroup

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 8c3a63d5064476803f7922f2dcb0f892a7fd763c..f1536e319b0fbe065a5094ba1823707815fc8f07 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -107,6 +107,7 @@ gtkseparator.sgml
 gtkseparatormenuitem.sgml
 gtkseparatortoolitem.sgml
 gtksettings.sgml
+gtksizegroup.sgml
 gtkstatusbar.sgml
 gtkstatusicon.sgml
 gtkstyle.sgml

diff --git a/docs/reference/gtk/tmpl/gtksizegroup.sgml b/docs/reference/gtk/tmpl/gtksizegroup.sgml
deleted file mode 100644 (file)
index 35b57b9..0000000
--- a/docs/reference/gtk/tmpl/gtksizegroup.sgml
+++ /dev/null
@@ -1,194 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkSizeGroup
-
-<!-- ##### SECTION Short_Description ##### -->
-Grouping widgets so they request the same size
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GtkSizeGroup provides a mechanism for grouping a number of widgets
-together so they all request the same amount of space.  This is
-typically useful when you want a column of widgets to have the same
-size, but you can't use a #GtkTable widget.
-</para>
-<para>
-In detail, the size requested for each widget in a #GtkSizeGroup is
-the maximum of the sizes that would have been requested for each
-widget in the size group if they were not in the size group. The mode
-of the size group (see gtk_size_group_set_mode()) determines whether
-this applies to the horizontal size, the vertical size, or both sizes.
-</para>
-<para>
-Note that size groups only affect the amount of space requested, not
-the size that the widgets finally receive. If you want the widgets in
-a #GtkSizeGroup to actually be the same size, you need to pack them in
-such a way that they get the size they request and not more. For
-example, if you are packing your widgets into a table, you would not
-include the %GTK_FILL flag.
-</para>
-<para>
-#GtkSizeGroup objects are referenced by each widget in the size group,
-so once you have added all widgets to a #GtkSizeGroup, you can drop
-the initial reference to the size group with g_object_unref(). If the
-widgets in the size group are subsequently destroyed, then they will
-be removed from the size group and drop their references on the size
-group; when all widgets have been removed, the size group will be
-freed.
-</para>
-<para>
-Widgets can be part of multiple size groups; GTK+ will compute the
-horizontal size of a widget from the horizontal requisition of all
-widgets that can be reached from the widget by a chain of size groups
-of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the
-vertical size from the vertical requisition of all widgets that can be
-reached from the widget by a chain of size groups of type
-%GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH.
-</para>
-<para>
-Note that only non-contextual sizes of every widget are ever consulted
-by size groups (since size groups have no knowledge of what size a widget
-will be allocated in one dimension, it cannot derive how much height
-a widget will receive for a given width). When grouping widgets that
-trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: 
-the height for the minimum width will be the requested height for all 
-widgets in the group. The same is of course true when horizontally grouping
-width for height widgets.
-</para>
-<para>
-Widgets that trade height-for-width should set a reasonably large minimum width
-by way of GtkLabel:width-chars for instance. Widgets with static sizes as well 
-as widgets that grow (such as ellipsizing text) need no such considerations.
-</para>
-<refsect2 id="GtkSizeGroup-BUILDER-UI">
-<title>GtkSizeGroup as GtkBuildable</title>
-<para>
-Size groups can be specified in a UI definition by placing an
-&lt;object&gt; element with <literal>class="GtkSizeGroup"</literal>
-somewhere in the UI definition. The widgets that belong to the
-size group are specified by a &lt;widgets&gt; element that may
-contain multiple &lt;widget&gt; elements, one for each member
-of the size group. The name attribute gives the id of the widget.
-</para>
-<example>
-<title>A UI definition fragment with GtkSizeGroup</title>
-<programlisting><![CDATA[
-<object class="GtkSizeGroup">
-  <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
-  <widgets>
-    <widget name="radio1"/>
-    <widget name="radio2"/>
-  </widgets>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkSizeGroup ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkSizeGroup:ignore-hidden ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSizeGroup:mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### ENUM GtkSizeGroupMode ##### -->
-<para>
-
-</para>
-
-@GTK_SIZE_GROUP_NONE: 
-@GTK_SIZE_GROUP_HORIZONTAL: 
-@GTK_SIZE_GROUP_VERTICAL: 
-@GTK_SIZE_GROUP_BOTH: 
-
-<!-- ##### FUNCTION gtk_size_group_new ##### -->
-<para>
-
-</para>
-
-@mode: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_size_group_set_mode ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@mode: 
-
-
-<!-- ##### FUNCTION gtk_size_group_get_mode ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_size_group_set_ignore_hidden ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@ignore_hidden: 
-
-
-<!-- ##### FUNCTION gtk_size_group_get_ignore_hidden ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_size_group_add_widget ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@widget: 
-
-
-<!-- ##### FUNCTION gtk_size_group_remove_widget ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@widget: 
-
-
-<!-- ##### FUNCTION gtk_size_group_get_widgets ##### -->
-<para>
-
-</para>
-
-@size_group: 
-@Returns: 
-
-

diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index 5a686a2d4ee3274307c67dc1b5ce287a5a3193d9..27324cf8812c84e1cf86eaeb22d2e5f67723dd4f 100644 (file)
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -29,6 +29,86 @@
 #include "gtksizegroup-private.h"
 #include "gtkwidgetprivate.h"
 
+
+/**
+ * SECTION:gtksizegroup
+ * @Short_description: Grouping widgets so they request the same size
+ * @Title: GtkSizeGroup
+ *
+ * #GtkSizeGroup provides a mechanism for grouping a number of widgets
+ * together so they all request the same amount of space.  This is
+ * typically useful when you want a column of widgets to have the same
+ * size, but you can't use a #GtkTable widget.
+ *
+ * In detail, the size requested for each widget in a #GtkSizeGroup is
+ * the maximum of the sizes that would have been requested for each
+ * widget in the size group if they were not in the size group. The mode
+ * of the size group (see gtk_size_group_set_mode()) determines whether
+ * this applies to the horizontal size, the vertical size, or both sizes.
+ *
+ * Note that size groups only affect the amount of space requested, not
+ * the size that the widgets finally receive. If you want the widgets in
+ * a #GtkSizeGroup to actually be the same size, you need to pack them in
+ * such a way that they get the size they request and not more. For
+ * example, if you are packing your widgets into a table, you would not
+ * include the %GTK_FILL flag.
+ *
+ * #GtkSizeGroup objects are referenced by each widget in the size group,
+ * so once you have added all widgets to a #GtkSizeGroup, you can drop
+ * the initial reference to the size group with g_object_unref(). If the
+ * widgets in the size group are subsequently destroyed, then they will
+ * be removed from the size group and drop their references on the size
+ * group; when all widgets have been removed, the size group will be
+ * freed.
+ *
+ * Widgets can be part of multiple size groups; GTK+ will compute the
+ * horizontal size of a widget from the horizontal requisition of all
+ * widgets that can be reached from the widget by a chain of size groups
+ * of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the
+ * vertical size from the vertical requisition of all widgets that can be
+ * reached from the widget by a chain of size groups of type
+ * %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH.
+ *
+ * Note that only non-contextual sizes of every widget are ever consulted
+ * by size groups (since size groups have no knowledge of what size a widget
+ * will be allocated in one dimension, it cannot derive how much height
+ * a widget will receive for a given width). When grouping widgets that
+ * trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH:
+ * the height for the minimum width will be the requested height for all
+ * widgets in the group. The same is of course true when horizontally grouping
+ * width for height widgets.
+ *
+ * Widgets that trade height-for-width should set a reasonably large minimum width
+ * by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well
+ * as widgets that grow (such as ellipsizing text) need no such considerations.
+ *
+ * <refsect2 id="GtkSizeGroup-BUILDER-UI">
+ * <title>GtkSizeGroup as GtkBuildable</title>
+ * <para>
+ * Size groups can be specified in a UI definition by placing an
+ * &lt;object&gt; element with <literal>class="GtkSizeGroup"</literal>
+ * somewhere in the UI definition. The widgets that belong to the
+ * size group are specified by a &lt;widgets&gt; element that may
+ * contain multiple &lt;widget&gt; elements, one for each member
+ * of the size group. The name attribute gives the id of the widget.
+ *
+ * <example>
+ * <title>A UI definition fragment with GtkSizeGroup</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkSizeGroup">
+ *   <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
+ *   <widgets>
+ *     <widget name="radio1"/>
+ *     <widget name="radio2"/>
+ *   </widgets>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </para>
+ * </refsect2>
+ */
+
+
 struct _GtkSizeGroupPrivate
 {
   GtkRequisition  minimum_req;